STIS DrizzlePac Tutorial

Learning Goals

By the end of this tutorial, you will:

Introduction

The Space Telescope Imaging Spectrograph (STIS) instrument on board the Hubble Space Telescope (HST) has three detectors: a charge-coupled device (CCD) and two multi-anode microchannel array (MAMA) detectors for near- and far-ultraviolet wavelengths (NUV MAMA and FUV MAMA respectively). The CCD detector suffers from charge transfer inefficiency (CTI) which can be corrected for directly on the CCD images using a pixel-based algorithm (stis_cti; based on work by Anderson & Bedin 2010, see webpage).

In order to maximize the science capabilities of images taken with STIS, they can be accurately aligned and combined (or 'drizzled'). The codes used to do this are from the DrizzlePac package which has been extensively tested on Wide-Field Camera 3 (WFC3) and Advanced Camera for Surveys (ACS) data but was previously unsupported for STIS. This tutorial gives alignment and drizzling examples for STIS images of standard star fields taken for each of its three detectors. We refer users to the DrizzlePac Handbook (Gonzaga et al. 2015, Hoffmann et al. 2021) for more details on the drizzling process and DrizzlePac codes.

STIS Data Formats

CCD data: For this example, only post-SM4 CCD data taken on primary science amplifier D are used. These are the best calibrated STIS CCD images, the default for science observations, and can be CTI corrected with the new pixel-based code stis_cti. For alignment and drizzling, we use STIS CCD images that have been fully calibrated (sx2.fits images: dark- and bias-subtracted, flat-fielded, sky-subtracted, summed individual cosmic-ray (CR) split images with CR-rejection and distortion corrections already applied) that have also been CTI corrected (s2c.fits images).

MAMA data: MAMA detectors do not require CTI corrections or CR-rejection, and STIS MAMA imaging is typically taken in single exposures (i.e., not CR split). For this example, we only use MAMA data with one science extension (i.e., three extensions total: SCI, ERR, DQ) as is typical for STIS MAMA data. If the MAMA data has more than one science extension (NEXTEND>3), the science extensions can be summed and saved as a new fits file with this as the first (and only) science extension. These should also be available as sfl.fits images from MAST where this is relevant. For alignment and drizzling, we use STIS MAMA images that have been fully calibrated (x2d.fits: dark- and bias-subtracted, flat-fielded, sky-subtracted, distortion corrections already applied).

Typically tweakreg and astrodrizzle require individual dark- and bias-subtracted, flat-fielded images (flt.fits), as for WFC3 and ACS. For STIS data, a few workarounds are required to ensure these codes can run on the STIS data. Additionally, specific parameters are set to ensure that additional calibrations (e.g, sky subtraction, CR-rejection, distortion corrections) are not applied to the already calibrated STIS data.

See the STIS Instrument Handbook and STIS Data Handbook (specifically Section 2.2 on file types) for more information.

Setting up the Conda Environment

The following commands may be used to reproduce the Python environment used to generate and test this Notebook.

Imports

Set & Make Directories

Set root directory for project (root_dir), a reference file directory (ref_dir, explained in more detail below but set this path to any existing reference file directories if present), and a cache directory for temporary data storage for downloads (cache_dir). The remaining directories will be nested within the root directory and are created below.

Setting Up Reference File Directory

STScI codes (e.g., stis_cti, DrizzlePac) need to access reference files to ensure the HST data they run on are properly calibrated. A local store for the reference files is required and a systerm variable should be set for the codes to access those files. The directory variable for STIS data is called "oref" by convention.

We create the oref environment variable first and populate it with the necessary reference files later in the Notebook. If you already have the required STIS reference files in an existing oref directory, set the oref environment variable to that directory path.

We can assign a system variable in three different ways, depending on whether we are working from:

  1. The command line
  2. A Python/Jupyter environment
  3. A Jupyter Notebook
Unix-style Command Line Python/Jupyter Jupyter Notebook
export oref='./reference_files/references/...' os.environ[\'oref\'] = \'./reference_files/references/...\' %env oref ./reference_files/references/...

Note that this system variable must be set again with every new instance of a terminal or Notebook or the export command can be added to your .bash_profile or equivalent file.

The Calibration Reference Data System (CRDS) both stores the reference files and determines the mapping of reference files to observations. The crds tool can find, update, and download the best reference files for a particular observation. The documentation for crds describes many of the more advanced options. In this Notebook we provide a demonstration on how to obtain updated reference file information stored in the FITS headers of observations and download those files to a local reference file directory.

First the following environment variables are needed:

Downloading Data

The data used in this example are from STIS monitoring observations of two standard star fields: NGC 5139 for the CCD and NGC 6681 for the MAMAs. We use two programs for each field from 2010 and 2011. The data are taken at the same position angle (PA) with some dithering and in the following filters:

The data are downloaded from MAST using astroquery, ~288 MB of data for the CCD and ~437 MB of data for the MAMAs.

Download Reference Files

The reference files for the STIS images are then updated in the image headers and downloaded (~250 MB). While the crds.bestrefs tool is also accessible inside of Python, it was designed with a command line interface in mind, therefore it is easiest to use it this way.

CTI Correct CCD Images

A pixel-based CTI correction is applied to the STIS CCD data with stis_cti. At present, this code can only be run on post-Servicing Mission 4 (SM4 in 2009) CCD data taken on the default science amplifier D. For all other CCD data, the previous empricial method (stistools.ctestis) can be used.

First the necessary files are copied over to the CTI correction directory. Then the darks needed to correct the data are determined and downloaded (about ~1.2 GB of data). Then the stis_cti code is run, see this webpage for a full description of the parameters. The num_processes parameter is the maximum number of parallel processes to use when running stis_cti, adjust this as needed for your machine.

Run checks on and inspect the CCD CTI corrected images.

File Information

Information is pulled from file headers and combined into a dataframe. The information is used for file sorting and determining appropriate alignment and drizzle parameters. We select only CCD data taken with primary science amplifier D and MAMA data with only one science extension for this example (see the Introduction - STIS Data Formats section for more details).

Image Alignment

Use tweakreg to align the images from the three STIS detectors to sub-pixel accuracy.

Tips and Tricks for Using tweakreg

Select Reference Images

Based on the dataframe of image properties in the File Summary section, identify an appropriate reference image (ref_img) for each detector (see Tips and Tricks for Using tweakreg section above). Adjust tweakreg parameters per detector to accurately align images onto the reference image. Set update=False for testing and change to update=True for final run to update image headers.

CCD (CTI Corrected) Image Alignment

Parameters tested for a couple of different exposure times are given below: <=10s and 60s.

Alignment accuracy for these images ranges between ~0.04--0.2 pixels, with average ~0.11 pixels.

NUV MAMA Image Alignment

Parameters tested for a couple of different exposure times are given below as a guide: 300 to <1000s (used here) and >=1000s. For other 300s images spanning 25 years of STIS data (only two programs used here), adjusting the convolution width (e.g., conv_width=4.5, 5.5, 6.5) for specific files enabled an alignment solution to be found. One file (obmi01xqq_x2d.fits in ofiles) has an offset from the reference image and required different parameters to find an alignment solution.

Alignment accuracy for these images ranges between ~0.1--0.5 pixels, with average ~0.3 pixels. These values are higher than the CCD partly due to the larger number of sources and that the MAMA data span three filters.

FUV MAMA Image Alignment

Parameters tested for a couple of different exposure times are given below as a guide: 400s to <1000s (used here), and >=1000s. For other images spanning 25 years of STIS data (only two programs shown here), adjusting the convolution width (e.g., conv_width=4.5, 5.5, 6.5) for specific files enabled an alignment solution to be found. Two files (obmi01y8q_x2d.fits, obmi01yaq_x2d.fits in ofiles) have an offset from the reference image and required different parameters to find an alignment solution.

Alignment accuracy for these images ranges between ~0.1--0.4 pixels, with average ~0.18 pixels. These values are slightly higher than the CCD as the MAMA data span three filters and the FUV MAMA has a broader PSF.

Testing Alignment Parameters

Below is useful code for testing tweakreg alignment parameters. If an image has been able to be matched (even if updatehdr=False) a <rootname>_shifts.txt file will be created. This code can be used to plot the sources used for alignment on the input image. Use this to verify the quality of sources used for alignment.

Drizzling Images

Next, the images for each detector are combined using astrodrizzle. The high-level concept behind drizzling images is described in detail in Section 3.2 of the DrizzlePac Handbook.

Setting the appropriate final_scale and final_pixfrac parameters for your images takes some thought and testing to avoid gaps in the data. The figure below shows a basic example of the native pixel scale (red squares), shrink factor final_pixfrac (blue squares) and output final pixel scale final_scale (grid on right) in a drizzle. For more details on the astrodrizzle input parameters, see the the DrizzlePac code webpages. Drizzle

astrodrizzle can be used to increase the pixel sampling of data if images have dithering and different position angles (PAs). For the STIS data used here, all images are at the same PA and therefore sub-sampling the data is not possible. The example for the STIS data shown below adopts the native pixel scale of each detector as the final_scale and no fractional scaling down of each pixel (final_pixfrac=1.0) prior to drizzling. Drizzle in this context is a useful tool for creating mosaics of images aligned with tweakreg.

To ensure that astrodrizzle does not apply additional calibrations to the already calibrated STIS data, Steps 1-6 can be 'switched off' using the appropriate keywords (see astrodrizzle webpage for keyword information). The CCD data are already CR-rejected and the MAMA data don't require this step, therefore many of those first steps (and their associated keywords) are to do with appropriately applying CR-rejection. Therefore the 'minmed' warning is not important for the STIS images.

Only data in a single filter for each detector are combined in this example: 50CCD (CCD), F25SRF2 (NUV MAMA), 25MAMA (FUV MAMA). STIS data have cleaned edges after the distortion correction is applied in the calstis pipeline. These are adaptively cropped out with the crop_edges function defined below for each image to avoid gaps in the final mosaics.

astrodrizzle changes the input image files, so it's advisable to first copy the data to a clean directory prior to drizzling (as done below). If you need to repeat the drizzling process, it's good practice to make another clean directory prior to running astrodrizzle.

CCD (CTI Corrected) Image Drizzling

The CCD images are all observed at a common position angle and RA/Dec with small dithers (hence poorer quality edges in the mosaic below). Sub-sampling the images with astrodrizzle is not advisable for these programs as reducing the pixel size results in gaps in the data.

Figure shows the CCD drizzle of NGC 5139 (left) and the individual CCD reference image used for alignment (right). CCD Drizzle

NUV MAMA Image Drizzling

The NUV images are all observed at a common position angle with large dithers (hence different image depths in the mosaic below). Sub-sampling the images with astrodrizzle is not advisable for these programs as reducing the pixel size results in gaps in the data.

Figure shows the NUV drizzle of NGC 6681 (left) and the individual NUV reference image used for alignment (right).

NUV Drizzle

FUV MAMA Image Drizzling

The FUV images are all observed at a common position angle with large dithers (hence different image depths in the mosaic below). Sub-sampling the images with astrodrizzle is not advisable for these programs as reducing the pixel size results in gaps in the data.

Figure shows the FUV drizzle of NGC 6681 (left) and the individual FUV reference image used for alignment (right). FUV Drizzle

About this Notebook

Author: Laura Prichard, Staff Scientist II, STIS Team.

Written: 2022-03-22

For questions on using the DrizzlePac package with STIS data, contact the HST Help Desk (help@stsci.edu).

Citations

Top of Page Space Telescope Logo